Request FolderSync when hierarchy is invalid during PING

Summary

When the server invalidates the folder hierarchy synckey in the device sync cache (for example after task list or calendar folder changes in a groupware app), clients were only forced to run FolderSync on the next SYNC request. PING could continue for minutes without telling the device to refresh its folder hierarchy, so new or removed folders did not appear until the user triggered an unrelated sync (e.g. editing a task).

This change aligns PING with the existing SYNC behaviour (ActiveSync 12.1+): if haveHierarchy() is false, return FolderSync required instead of waiting in pollForChanges().

Changes

lib/Horde/ActiveSync/Request/Ping.php

Before entering the PING wait loop, if the device protocol version is ≥ 12.1 and the sync cache has no valid hierarchy synckey (!haveHierarchy()), respond immediately with PING status 7 (STATUS_FOLDERSYNCREQD) and stop processing.

This mirrors the check already present at the start of Horde_ActiveSync_Request_Sync for STATUS_FOLDERSYNC_REQUIRED (12).

lib/Horde/ActiveSync/Collections.php

At the beginning of pollForChanges(), if the device is ≥ 12.1 and haveHierarchy() is false, return COLLECTION_ERR_FOLDERSYNC_REQUIRED so any PING path that reaches the poll loop also terminates with FolderSync required (same outcome as the explicit handling in Ping.php).

Why version ≥ 12.1

The hierarchy synckey in Horde_ActiveSync_SyncCache and the associated status codes are part of the ActiveSync 12.1 folder hierarchy model. Older clients use a different folder sync flow; Horde already gates the SYNC-side check on VERSION_TWELVEONE ('12.1'). Both Ping.php and Collections.php use the same guard so clients ≤ 12.0 are unchanged.

Behaviour notes

• Invalidating hierarchy means setting the cache hierarchy value to empty/'0' (see SyncCache::__isset / haveHierarchy()), not clearing the folder cache.
• PING status 7 and COLLECTION_ERR_FOLDERSYNC_REQUIRED were already handled in Ping.php; this change ensures the condition is detected before a long heartbeat wait.
• A cache timestamp bump alone (COLLECTION_ERR_STALE) only ends PING early; it does not instruct the client to run FolderSync.

Test plan

• Device on ActiveSync 12.1+ (e.g. iOS Mail/Tasks): invalidate hierarchy on server (demux task lists or similar), confirm next PING returns FolderSync required (status 7) in server log.
• Confirm FolderSync runs and delivers FolderHierarchy:Add / Remove as appropriate.
• Confirm normal PING/SYNC still works when hierarchy synckey is valid.
• No change expected for clients < 12.1 (guard not applied).

Related work

Companion changes in Nag (separate PR): web-side task list create/delete updates sync_lists and invalidates hierarchy without pruning device folder cache before FolderSync.